Additive public API (maintainer-approved): Client::captureException() and the static facade accept options['source'], emitted as event-level $exception_source. It is independent of semantic mechanism.type and handled; it never sets nested mechanism.source. Invalid/missing typed source is omitted, and generic additional/ambient property bags cannot supply provenance.

💡 Motivation and Context

Framework integrations need to keep context active across before/after callbacks, report failed boundaries accurately, and use a client instance without changing the global default.

This is the first PR in a Laravel integration stack. It adds reusable PHP SDK support only:

• Add Client::groupIdentify() and delegate the static facade to it.
• Add enterContext() and an idempotent closeable scope. Scopes preserve client and Fiber isolation, including cleanup from another execution path.
• Allow framework exception capture to supply handled/mechanism metadata while preserving the original exception chain and stack. Existing manual capture stays handled by default.
• Add @internal protected Client::libraryName(), libraryVersion() and releaseId() overrides for PostHog framework integrations (library metadata, and release IDs from cached application configuration). These are not constructor options, so customers keep POSTHOG_RELEASE_ID as the only documented release ID input. Event properties still take precedence.

Public API changes are recorded in the API snapshot. Capture, group-identify, exception metadata and tracing-header specs apply. The optional framework boundary metadata extends the manual exception API without changing its default handled behavior.

💚 How did you test it?

• Added framework tests first and confirmed the missing APIs and handled-state assertion failed before implementation.
• Full PHP suite after the human review follow-up: 2,532 tests, 11,366 assertions.
• Focused framework and configured batch transport suites: 48 tests, 211 assertions.
• PHP_CodeSniffer for all changed PHP files, API snapshot check and git diff --check pass.
• Initial isolated autoreview of 34e07100d9ce06f2c56312a9d1072a59574ffed8 against origin/main reported no actionable findings.

Review follow-up 8773c43 addresses all three bot findings with failing-before/passing-after regressions: configured batch User-Agents (including safe shell/header handling), abandoned Fiber cleanup without retention or object-ID identity reuse, and independently validated exception metadata overrides. The 16 adapter tests also pass. These fixes follow the HTTP client and exception-event-metadata contracts; unrelated Retry-After compliance report failures remain outside this framework PR.

📝 Checklist

• All commits are signed.
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm change to generate a change intent file.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Implemented with Pi using local file tools, PHP/Composer, Git and GitHub CLI. A separate isolated Pi review checked the final core diff. The user requested an independently released Laravel package depending on the PHP SDK, with stacked PRs and an example application. Framework lifecycle and payload support live in the core so the package does not duplicate them. Human review is required before merge.

Stack

Merge bottom-up:

1. feat: add PHP framework integration primitives #282: PHP framework support
2. feat: add the Laravel runtime package #283: Laravel runtime
3. feat: add opt-in Laravel autocapture #284: Optional server autocapture
4. feat: integrate PostHog feature flags with Laravel Pennant #285: Read-only Pennant integration
5. feat: add a runnable Laravel SDK example #286: Runnable Laravel example
6. ci: release the Laravel package independently #287: Independent CI and publishing

Laravel source lives in this repository but its Composer package is released separately. Publish core ^4.20 first. The distribution repository, protected release environment and Packagist setup remain administrator prerequisites. No release has been published.

Follow-up ecbc8cc supplies the internal context-bound snapshot host needed by #283's lazy-exposure feedback. Four regressions failed before the fix (later-session leakage and unscoped snapshots inheriting later context), then passed; the combined flag/framework suites pass 491 tests / 1,899 assertions. A fresh read-only review of this exact commit found no actionable issues. API shape is unchanged. PHP 8.2–8.5, coverage, style, API, and security CI checks pass.

Human review follow-up 858c204

• Invalid instance group identity now logs a validation warning and returns false, without enqueueing a group event. Static-facade type/key validation keeps its original exceptions/messages. Six real SDK throw reproductions are now green.
• The typed source channel follows the pinned exception metadata contract: e.g. mechanism=middleware, source=laravel.middleware, handled=false. No derivation between these independent fields or guessing from libraries/stack frames. Eleven source regressions failed before (ignored typed metadata/property-bag spoofing), then passed, including normal static forwarding, invalid override omission, context/session preservation and before_send provenance.
• Scope class/close and both enterContext docs explain retained ownership, immediate destruction if discarded, idempotence and younger-scope preservation. A retained regression confirms discard behavior; existing lifecycle/Fiber cases remain green.
• Nineteen tests were added, plus default-library provenance assertions. Focused 20 tests / 176 assertions; full SDK 2,532 / 11,366. API snapshot remains current because PHP signatures are unchanged; the new array option is documented explicitly. The existing minor change intent covers framework metadata. Scoped style checks pass with zero new warnings; the legacy PostHogTest file retains the same 23 existing non-fixable warnings. Independent isolated review is clean.
• Signed bottom-up merges preserve the complete Laravel stack. Final committed-source Laravel 12/13 matrices each pass 106 package tests / 664 assertions and 29 example tests / 163 assertions; all 13 release-tooling tests pass.
• This core follow-up adds the explicit channel; existing Laravel forwarding can pass it. Automatic Laravel hook-specific source selection is not claimed as implemented here.

Before the first Laravel release: server SDK registration

posthog-laravel is not yet registered on PostHog server master for PHP usage attribution, Python/Rust feature-flag library classification/parser, or SDK health frontend/backend registries. A separate backend registration/alias PR must land before the Laravel package ships, following the approach in PostHog/posthog#93911. Event ingestion itself is not rejected just because this library identifier is unclassified. SDK health/version handling must respect Laravel's independent package version, not compare 0.1.x against PHP core 4.x. No backend PR, repository or release was created by this SDK follow-up; this remains an explicit pre-release prerequisite alongside core ^4.20 publication and distribution/Packagist setup.